GitLab 进阶：.gitlab-ci.yml 配置文件编写
核心概念
GitLab CI/CD 通过项目根目录下的 .gitlab-ci.yml 文件驱动整个流水线。这是一个 YAML 格式的配置文件，定义了流水线的结构、环境和执行步骤。
Pipeline 架构
Pipeline（流水线）
├── Stage: build（构建阶段）
│ ├── Job: build-job
│ └── Job: compile-job
├── Stage: test（测试阶段）
│ ├── Job: lint-test（并行执行）
│ └── Job: unit-test（并行执行）
└── Stage: deploy（部署阶段）
└── Job: deploy-job
text
关键规则：
- 同一 Stage 中的 Job 并行执行
- 不同 Stage 按顺序执行
- 前一 Stage 失败，后续 Stage 不会执行
配置文件关键字参考
全局关键字
| 关键字 | 说明 | 示例 |
|---|---|---|
stages | 定义阶段顺序 | stages: [build, test, deploy] |
default | 设置默认值 | default: { image: node:18 } |
image | 全局默认镜像 | image: node:18-alpine |
variables | 全局变量 | variables: { NODE_ENV: "production" } |
cache | 全局缓存 | 缓存 node_modules 等 |
before_script | 前置脚本 | 所有 Job 执行前运行 |
after_script | 后置脚本 | 所有 Job 执行后运行 |
workflow | 流水线规则 | 控制整个流水线的运行条件 |
Job 关键字
| 关键字 | 说明 | 示例 |
|---|---|---|
stage | 所属阶段 | stage: build |
script | 执行脚本 | script: [npm install, npm run build] |
image | 指定镜像 | image: node:18-alpine |
variables | Job 级变量 | variables: { API_URL: "..." } |
artifacts | 制品配置 | artifacts: { paths: [dist/] } |
cache | 缓存配置 | cache: { paths: [node_modules/] } |
rules | 运行规则 | rules: [{ if: $CI_COMMIT_BRANCH == "main" }] |
tags | Runner 标签 | tags: [docker] |
needs | 无序执行 | 跳过阶段顺序，直接依赖 |
when | 触发条件 | when: manual（手动触发） |
allow_failure | 允许失败 | allow_failure: true |
retry | 重试次数 | retry: 2 |
timeout | 超时设置 | timeout: 1h |
基础模板示例
最简流水线
# .gitlab-ci.yml
stages:
- build
- test
- deploy
build-job:
stage: build
script:
- echo "Building the application..."
- sleep 60
lint-test:
stage: test
script:
- echo "Running lint tests..."
- sleep 10
unit-test:
stage: test
script:
- echo "Running unit tests..."
- sleep 10
deploy-job:
stage: deploy
script:
- echo "Deploying application..."
- sleep 10
yaml
这个模板包含三个阶段，其中 test 阶段有两个并行任务。
使用在线编辑器
GitLab 提供了流水线在线编辑器：
- 进入项目 -> Build > Pipeline editor
- 点击 Configure pipeline
- 编辑 YAML 配置
- 点击 Validate 验证语法
- 点击 Commit changes 提交
编辑器顶部有三个标签页：
- Edit：编辑 YAML 文件
- Visualize：可视化查看各阶段和任务
- Validate：验证流水线语法
阶段（Stages）配置
stages:
- build # 第1阶段：构建
- test # 第2阶段：测试（可并行多个 Job）
- staging # 第3阶段：预发布
- deploy # 第4阶段：正式部署
yaml
自定义阶段
stages:
- .pre # 内置阶段：始终最先执行
- build
- test
- deploy
- .post # 内置阶段：始终最后执行
yaml
.pre和.post是 GitLab 内置阶段，无需在 stages 中声明即可使用。
镜像（Image）配置
# 全局默认镜像
default:
image: node:18-alpine
build-job:
stage: build
script:
- node --version
- npm --version
# Job 级别覆盖镜像
docker-build:
stage: build
image: docker:24-cli
script:
- docker --version
yaml
使用服务容器
test-job:
stage: test
image: node:18-alpine
services:
- name: postgres:15
alias: db
- name: redis:7
alias: cache
variables:
POSTGRES_DB: test_db
POSTGRES_USER: test
POSTGRES_PASSWORD: test
script:
- npm test
yaml
脚本（Script）配置
build-job:
stage: build
before_script:
- echo "Preparing environment..."
- npm config set registry https://registry.npmmirror.com
script:
- npm install
- npm run build
after_script:
- echo "Build completed with status $CI_JOB_STATUS"
yaml
| 关键字 | 执行时机 | 是否可使用变量 |
|---|---|---|
before_script | script 之前 | 是 |
script | 主体执行 | 是 |
after_script | 无论成功失败都执行 | 仅预定义变量 |
制品（Artifacts）配置
build-job:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/ # 保存 dist 目录
- build/report.html # 保存构建报告
exclude:
- dist/*.map # 排除 sourcemap
expire_in: 1 week # 过期时间
when: on_success # 成功时保存
yaml
artifacts.when 选项
| 值 | 说明 |
|---|---|
on_success | 仅成功时保存（默认） |
on_failure | 仅失败时保存 |
always | 总是保存 |
缓存（Cache）配置
default:
cache:
key:
files:
- package-lock.json
prefix: $CI_COMMIT_REF_SLUG
paths:
- node_modules/
policy: pull-push
install-job:
stage: build
script:
- npm ci
cache:
policy: push # 仅写入缓存
build-job:
stage: build
script:
- npm run build
cache:
policy: pull # 仅读取缓存
yaml
变量（Variables）配置
定义变量
# 全局变量
variables:
APP_NAME: "my-vue-app"
BUILD_ENV: "production"
# Job 级别变量
deploy-job:
stage: deploy
variables:
DEPLOY_TARGET: "staging"
script:
- echo "Deploying $APP_NAME to $DEPLOY_TARGET"
yaml
常用预定义变量
| 变量 | 说明 |
|---|---|
$CI_COMMIT_BRANCH | 当前提交分支 |
$CI_COMMIT_SHA | 当前提交 SHA |
$CI_COMMIT_REF_SLUG | 分支名（URL 安全） |
$CI_DEFAULT_BRANCH | 默认分支名 |
$CI_PROJECT_ID | 项目 ID |
$CI_PROJECT_DIR | 项目目录路径 |
$CI_JOB_TOKEN | Job 令牌（用于认证） |
$CI_REGISTRY | Container Registry 地址 |
$CI_REGISTRY_USER | Registry 用户名 |
$CI_REGISTRY_PASSWORD | Registry 密码 |
$CI_API_V4_URL | GitLab API v4 URL |
注意：不同变量有最低 GitLab 版本要求，使用前请查阅官方 Predefined Variables Reference。
CI/CD 变量设置
除了在配置文件中定义，还可在 GitLab 界面设置敏感变量：
- 进入项目 -> Settings > CI/CD > Variables
- 点击 Add variable
- 配置 Key/Value
- 设置属性：
- Protected：仅在保护分支中可用
- Masked：日志中隐藏值
- Expand variable reference：展开变量引用
规则（Rules）与条件
deploy-production:
stage: deploy
script:
- echo "Deploy to production"
rules:
# 仅在 main 分支触发
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: on_success
deploy-staging:
stage: deploy
script:
- echo "Deploy to staging"
rules:
# 仅在 develop 分支触发
- if: $CI_COMMIT_BRANCH == "develop"
manual-deploy:
stage: deploy
script:
- echo "Manual deployment"
rules:
# 手动触发
- if: $CI_COMMIT_BRANCH =~ /^release\//
when: manual
allow_failure: true
yaml
完整实战示例
# .gitlab-ci.yml - Node.js 项目完整流水线
stages:
- install
- build
- test
- deploy
default:
image: node:18-alpine
variables:
npm_config_registry: https://registry.npmmirror.com
# 安装依赖
install-deps:
stage: install
script:
- npm ci --cache .npm --prefer-offline
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
- .npm/
# 构建项目
build-job:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 day
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
policy: pull
# 代码检查
lint-job:
stage: test
script:
- npm run lint
cache:
policy: pull
# 单元测试
test-job:
stage: test
script:
- npm run test:unit
coverage: '/Statements\s*:\s*(\d+\.?\d*)%/'
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage/cobertura-coverage.xml
# 部署
deploy-job:
stage: deploy
image: alpine:latest
before_script:
- apk add --no-cache rsync openssh-client
- mkdir -p ~/.ssh
- echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
- chmod 600 ~/.ssh/id_rsa
script:
- rsync -avz --delete dist/ user@server:/var/www/html/
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
tags:
- docker
yaml
配置技巧
- 善用 Pipeline Editor：在线编辑器提供语法验证和可视化预览
- 查阅 Keyword Reference：官方提供完整的关键字参考文档
- 参考 Examples：GitLab 官方 CI/CD Examples 涵盖绝大多数场景
- 注意版本兼容：部分关键字和变量有最低版本要求
- 分离配置：复杂流水线可使用
include拆分配置文件
课程实战配置
以下是一个实际用于 Vue 前端项目的 .gitlab-ci.yml 配置，采用两阶段流水线（build + deploy）：
stages:
- build
- deploy
build-job:
stage: build
image: node:18-alpine
script:
- npm install --registry=https://registry.npmmirror.com
- npm run build
- ls -la
artifacts:
untracked: false
when: on_success
expire_in: 30 days
paths:
- "dist/"
deploy-job:
stage: deploy
image: alpine
environment: production
script:
- sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
- apk add --no-cache rsync openssh
- mkdir -p ~/.ssh
- echo "$SSH_PRIVATE_KEY" >> ~/.ssh/id_rsa
- chmod 600 ~/.ssh/id_rsa
- echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
- rsync -rav --delete dist/ root@192.168.31.199:/home/front-end/dist
yaml
CI/CD 变量配置
部署任务中的 $SSH_PRIVATE_KEY 需要在 GitLab 项目中配置：
- 进入项目 -> Settings > CI/CD > Variables
- 添加变量
SSH_PRIVATE_KEY，值为目标服务器的 SSH 私钥 - 建议勾选 Masked，避免在日志中泄露
受保护分支
生产部署通常需要限制仅在保护分支（如 main）触发：
- 进入项目 -> Settings > Repository > Protected branches
- 配置允许推送和合并的角色
- 在
.gitlab-ci.yml的 deploy Job 中添加rules限制
常见环境 CI 模板参考
GitLab 官方提供了覆盖主流语言和框架的 CI/CD 模板，在项目初始化 Pipeline 时可直接选用：
| 环境 | 模板文件 |
|---|---|
| Node.js | Nodejs.gitlab-ci.yml |
| npm | npm.gitlab-ci.yml |
| Docker | Docker.gitlab-ci.yml |
| Python | Python.gitlab-ci.yml |
| Go | Go.gitlab-ci.yml |
| Android | Android.gitlab-ci.yml |
| iOS (fastlane) | iOS-Fastlane.gitlab-ci.yml |
| Rust | Rust.gitlab-ci.yml |
完整模板列表见 GitLab CI/CD Templates。
配置技巧
- 善用 Pipeline Editor：在线编辑器提供语法验证和可视化预览
- 查阅 Keyword Reference：官方提供完整的关键字参考文档
- 参考 Examples：GitLab 官方 CI/CD Examples 涵盖绝大多数场景
- 注意版本兼容：部分关键字和变量有最低版本要求
- 分离配置：复杂流水线可使用
include拆分配置文件
参考资源
↑